Conv3DS Release Notes
---------------------

Instructions
------------

* Purpose of this utility

The Conv3DS utility converts one or more Autodesk 3D Studio Release 4 files
(which have a .3DS extension) to a single Kuju Shape file (which has a .S
extension).

Each 3DS file which contributes to the resulting S file describes a level of
detail (or LOD, also sometimes called distance levels) of the shape being
created. Each level of detail has a maximum distance from the camera at which
it will be used (sometimes called its visible distance).  The visible distance
must be included in the filename of each 3DS file.  For example if the shape
is called 'loco' and there are four LODs, at 50m, 100m, 200m and 400m
respectively then the four 3DS files will need to be named as follows:

loco50.3ds
loco100.3ds
loco200.3ds
loco400.3ds

* Usage

Conv3DS is a command-line utility, that is it must be used from a DOS or
command prompt window within Windows or using the Run option on the Start
Menu.  The Conv3DS command-line is constructed as follows:

Conv3DS <output file> <input files>

The output filename is formatted as follows:

<base>.s

Where <base> is the base name of the shape.

The input filenames are formatted in the following manner and separated
by spaces:

<base><visdist>.3ds

<base> is the base name of the shape and <visdist> is the visible distance of
the LOD contained within the file.


* Examples

Conv3DS loco.s loco50.3ds loco100.3ds loco200.3ds loco400.3ds

This will take the four input 3DS files and create the Kuju shape file
"loco.s" with four LODs at 50m, 100m, 200m and 400m.

* Notes

Even in the case where you are creating only a single LOD it is important to
provide the visible distance as this will determine the ultimate distance at
which the object is visible.

If you are using filenames which contain spaces then you must enclose each
filename in double quotes e.g.

Conv3DS "My First Loco.s" "My First Loco 50.3ds" "My First Loco 100.3ds"

Please ensure that the base element of the 3DS file name does not end with a
numeric digit for example where your shape is called dash9 and the
visible distance for this LOD is 50m calling that file dash950.3ds will result
in the visible distance for that LOD being set to 950m.  Therefore it is
suggested you separate the visible distance element of the 3DS file name from
the rest in this case with a non-numeric character, e.g. in the previous
example dash9_50.3ds would work correctly and result in that LOD having a
visible distance of 50m.

Additionally please ensure that there are no other characters between the
visible distance and the .3DS file extension in the filename.  For example,
acela200m.3ds would not work, but acela200.3ds would be fine.

Due to the limitation of the length of node names in the 3DS format it has
been necessary to introduce a translation step into the conversion process.
The following translations will take place.

Name in .3DS file             Name in .S file
PANTOBOT1                     PANTOGRAPHBOTTOM1
PANTOTOP1                     PANTOGRAPHTOP1
PANTOBOT2                     PANTOGRAPHBOTTOM2
PANTOTOP2                     PANTOGRAPHTOP2
PANTOBOT1A                    PANTOGRAPHBOTTOM1A
PANTOMID1A                    PANTOGRAPHMIDDLE1A
PANTOTOP1A                    PANTOGRAPHTOP1A
PANTOBOT1B                    PANTOGRAPHBOTTOM1B
PANTOMID1B                    PANTOGRAPHMIDDLE1B
PANTOTOP1B                    PANTOGRAPHTOP1B
PANTOBOT2A                    PANTOGRAPHBOTTOM2A
PANTOMID2A                    PANTOGRAPHMIDDLE2A
PANTOTOP2A                    PANTOGRAPHTOP2A
PANTOBOT2B                    PANTOGRAPHBOTTOM2B
PANTOMID2B                    PANTOGRAPHMIDDLE2B
PANTOTOP2B                    PANTOGRAPHTOP2B
WIPERARML1                    WIPERARMLEFT1
WIPEBLADL1                    WIPERBLADELEFT1
WIPERARMR1                    WIPERARMRIGHT1
WIPEBLADR1                    WIPERBLADERIGHT1
WIPERARML2                    WIPERARMLEFT2
WIPEBLADL2                    WIPERBLADELEFT2
WIPERARMR2                    WIPERARMRIGHT2
WIPEBLADR2                    WIPERBLADERIGHT2




Update History
---------------


* Fixed problem caused by triangles with coincident vertices breaking the 
  face/vertex normal generation

* Improved error message for case when mesh contains isolated vertices which
  prevents successful file conversion.

* Fixed problem where having a mix of untextured and textured nodes could in
  some circumstances cause a crash.  A warning message is now displayed.

* Fixed a bug which caused Conv3DS to hang or crash when attempting to convert
  a multi-node object with multiple LODs.

* Fixed problem with filename parsing where filenames containing multiple
  numbers separated by non-numeric characters resulted in the first number
  being used for the visible distance for that LOD.

* Fixed problem where 3DS pivots were not being intepreted correctly.

* Added conversion of short 3DS-compatible node names to long MSTS-compatible
  node names.

* Made matrix orthonormality test less rigorous to avoid false reports that
  node matrices contained a scale and/or reflection.

* Fixed filename handling such that they can now contain backslash characters
  and therefore paths.

* Fixed handling of 3DS objects with one mesh and no nodes so that they can
  now be exported.

* Fixed problem where invalid vertex normals were being generated in some
  cases.

* Fixed format of animation rotation keys.


